/**
 * @file network_utils.h
 * @brief 104协议网络工具模块头文件
 * @details 本文件提供了104协议网络工具模块的接口定义，包括TCP网络连接、
 *          数据收发、连接管理等功能。实现完整的网络通信接口，支持
 *          客户端连接、数据传输、连接状态管理和错误处理。
 * 
 *          主要功能包括：
 *          - 网络连接：建立和维护TCP连接
 *          - 数据收发：发送和接收网络数据
 *          - 连接管理：管理连接状态和生命周期
 *          - 错误处理：处理网络错误和异常情况
 *          - 统计信息：记录网络通信相关的统计数据
 *          - 配置管理：管理网络连接配置参数
 * 
 * @author zyb
 * @date 2025-09-30
 * @version 1.0
 * 
 * @note 本模块是104协议应用程序的网络通信工具组件
 * @warning 所有函数都是线程安全的，使用互斥锁保护共享数据
 * @see protocol_interface.h
 * @see protocol_types.h
 */

#ifndef NETWORK_UTILS_H
#define NETWORK_UTILS_H

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 错误码定义 ==================== */

/**
 * @brief 网络操作结果类型
 * @details 定义网络操作的各种结果状态
 */
typedef enum {
    NETWORK_SUCCESS = 0,              /* 操作成功 */
    NETWORK_ERROR_INVALID_PARAM = -1, /* 无效参数 */
    NETWORK_ERROR_CONNECTION_FAILED = -2, /* 连接失败 */
    NETWORK_ERROR_SEND_FAILED = -3,   /* 发送失败 */
    NETWORK_ERROR_RECEIVE_FAILED = -4, /* 接收失败 */
    NETWORK_ERROR_TIMEOUT = -5,       /* 超时 */
    NETWORK_ERROR_DISCONNECTED = -6,  /* 连接断开 */
    NETWORK_ERROR_MEMORY = -7         /* 内存错误 */
} network_result_t;

/* ==================== 数据结构定义 ==================== */

/**
 * @brief 网络客户端配置结构
 */
typedef struct {
    char server_ip[16];        /* 服务器IP地址 */
    uint16_t server_port;      /* 服务器端口 */
    uint32_t timeout_ms;       /* 超时时间(毫秒) */
    uint32_t buffer_size;      /* 缓冲区大小 */
    bool auto_reconnect;       /* 自动重连 */
} network_config_t;

/**
 * @brief 网络客户端结构
 */
typedef struct {
    int socket_fd;             /* 套接字文件描述符 */
    network_config_t config;   /* 配置信息 */
    bool connected;            /* 连接状态 */
    uint32_t bytes_sent;       /* 发送字节数 */
    uint32_t bytes_received;   /* 接收字节数 */
    uint32_t connection_count; /* 连接次数 */
    uint32_t error_count;      /* 错误次数 */
} network_client_t;

/**
 * @brief 网络统计信息结构
 */
typedef struct {
    uint32_t total_connections;    /* 总连接数 */
    uint32_t successful_connections; /* 成功连接数 */
    uint32_t failed_connections;   /* 失败连接数 */
    uint32_t total_bytes_sent;     /* 总发送字节数 */
    uint32_t total_bytes_received; /* 总接收字节数 */
    uint32_t total_errors;         /* 总错误数 */
    uint32_t timeout_count;        /* 超时次数 */
} network_stats_t;

/* ==================== 函数声明 ==================== */

/**
 * @brief 初始化网络客户端
 * @details 初始化网络客户端，设置默认配置参数
 * 
 * @param client 网络客户端指针
 * @return 初始化结果
 */
network_result_t network_client_init(network_client_t *client);

/**
 * @brief 配置网络客户端
 * @details 设置网络客户端的连接参数
 * 
 * @param client 网络客户端指针
 * @param config 配置参数
 * @return 配置结果
 */
network_result_t network_client_configure(network_client_t *client, const network_config_t *config);

/**
 * @brief 连接到服务器
 * @details 建立与服务器的TCP连接
 * 
 * @param client 网络客户端指针
 * @return 连接结果
 */
network_result_t network_client_connect(network_client_t *client);

/**
 * @brief 断开连接
 * @details 断开与服务器的连接
 * 
 * @param client 网络客户端指针
 * @return 断开结果
 */
network_result_t network_client_disconnect(network_client_t *client);

/**
 * @brief 发送数据
 * @details 向服务器发送数据
 * 
 * @param client 网络客户端指针
 * @param data 数据缓冲区
 * @param length 数据长度
 * @return 发送结果
 */
network_result_t network_client_send(network_client_t *client, const uint8_t *data, uint32_t length);

/**
 * @brief 接收数据
 * @details 从服务器接收数据
 * 
 * @param client 网络客户端指针
 * @param buffer 接收缓冲区
 * @param buffer_size 缓冲区大小
 * @param received_length 实际接收长度
 * @return 接收结果
 */
network_result_t network_client_receive(network_client_t *client, uint8_t *buffer, uint32_t buffer_size, uint32_t *received_length);

/**
 * @brief 检查连接状态
 * @details 检查网络连接是否正常
 * 
 * @param client 网络客户端指针
 * @return 连接状态
 */
bool network_client_is_connected(const network_client_t *client);

/**
 * @brief 获取统计信息
 * @details 获取网络通信统计信息
 * 
 * @param client 网络客户端指针
 * @param stats 统计信息结构指针
 * @return 获取结果
 */
network_result_t network_client_get_stats(const network_client_t *client, network_stats_t *stats);

/**
 * @brief 销毁网络客户端
 * @details 清理网络客户端资源
 * 
 * @param client 网络客户端指针
 * @return 销毁结果
 */
network_result_t network_client_destroy(network_client_t *client);

#ifdef __cplusplus
}
#endif

#endif /* NETWORK_UTILS_H */
